Mosaic Form Support (DOS CGI version)

This is an edited version of the Mosaic for X forms document. It has been edited to serve as a reference source for DOS Scripting for Windows httpd.
Here are details about what the NCSA X Mosaic team have implemented for fill-out forms in Mosaic for X 2.0.

If you are unfamiliar with forms, you should jump to the examples and try them out.

Note: If you are reading this document in local file mode, click here to switch to network mode. Be sure your server is running. If it fails, your net package doesn't support "localhost" (mine doesn't, by the way). Otherwise, just open this document via network URL now.

The FORM Tag

The FORM tag specifies a fill-out form within an HTML document. More than one fill-out form can be in a single document, but forms cannot be nested.

<FORM ACTION="url"> ... </FORM>

The attributes are as follows:

NOTE: Your Windows httpd (X1.1a6 or later) supports the POST method, so you should use it. Mosaic for Windows V2.0a3 supports POST forms as well. Consider GET forms to be deprecated.

Inside a FORM you can have anything except another FORM. Specifically, INPUT, SELECT, and TEXTAREA tags are used to specify interface elements within the form.

Forms are not automatically visually differentiated from the rest of a document. We recommend using the <HR> (horizontal rule) tag before and after a form to cleanly differentiate it from surrounding text and/or other forms.

The INPUT Tag

The INPUT tag is used to specify a simple input element inside a FORM. It is a standalone tag; it does not surround anything and there is no terminating tag -- i.e., it is used in much the same way as IMG.

In Mosaic, the various types of INPUT tags are mapped to Motif "widgets" or to Windows "controls". The appearance is determined by the browser (naturally).

The attributes to INPUT are as follows:

The SELECT Tag

Inside <FORM> ... </FORM>, any number of SELECT tags are allowed, freely intermixed with other HTML elements (including INPUT and TEXTAREA elements) and text (but not additional forms). In Mosaic, SELECT tags are mapped to Motif option menus and scrolled lists or Windows menus and listboxes.

Unlike INPUT, SELECT has both opening and closing tags. Inside SELECT, only a sequence of OPTION tags -- each followed by an arbitrary amount of plain text (no HTML markup) -- is allowed; for example: 

        <SELECT NAME="a-menu">
        <OPTION> First option.
        <OPTION> Second option.
        </SELECT>
The attributes to SELECT are as follows:

The attributes to OPTION are as follows:

The TEXTAREA Tag

The TEXTAREA tag can be used to place a multiline text entry field with optional default contents in a fill-out form. The attributes to TEXTAREA are as follows:

TEXTAREA fields automatically have scrollbars; any amount of text can be entered in them.

The TEXTAREA element requires both an opening and a closing tag. A TEXTAREA with no default contents looks like this: 

        <TEXTAREA NAME="foo" ROWS=4 COLS=40></TEXTAREA>
A TEXTAREA with default contents looks like this: 

        <TEXTAREA NAME="foo" ROWS=4 COLS=40>
        Default contents go here.
        </TEXTAREA>
The default contents must be straight ASCII text. Newlines are respected (so in the above example there will be a newline both before and after "Default contents go here.").

Form Submission

For Method = POST (highly recommended!)

When the submit button is pressed, the contents of the form are sent in a data block as part of the POST operation. The data is URL-encoded. For example:

    name=value&name=value&name=value
The ACTION attribute (if any) is the URL to which the data block is POSTed.

Strange characters in any of the "name" or "value" instances will be escaped as usual; this includes "=" and "&". Note: This means that instances of "=" that separate names and values, and instances of "&" that separate name/value pairs, are not escaped.

For text and password entry fields, whatever the user typed in will be the value; if the user didn't type anything, the value will be empty but the "name=" part of the query string will still be present.

For checkboxes and radio buttons, the VALUE attribute specifies the value of a checkbox or radio button when it is checked. An unchecked checkbox is disregarded completely when assembling the query string. Multiple checkboxes can have the same NAME (and different VALUEs), if desired. Multiple radio buttons intended to have "one of many" behavior should have the same NAME and different VALUEs.

For Method = GET (not recommended!)

The contents of the form are encoded exactly as with the POST method (above), but the contents are appended to the URL specified by the form's ACTION attribute as a query. Obviously this can create a huge URL. It is for this reason that GET based forms are deprecated.

Test Servers

If you wish to write a prototype fill-out form and test it against a query server that simply shows you what you submitted (with name/value pairs decoded and itemized), you can use the following:

The fill-out form examples listed below use these query servers as their back ends, so you can see them in action and know what to expect with your own forms.

Important note: If you use the GET method in your form, you will notice that the example GET server will choke if too much data (more than a couple hundred bytes) is submitted at a time -- the server is passing the data to the form-processing module via a shell command line, and the maximum shell command line length is being exceeded. This problem does not exist with the POST method and server.

Things To Note

ISINDEX Handling

An ISINDEX is displayed as a preloaded fill-out form suitable for entering a query. In Mosaic for X, the form is inlined at the location of the ISINDEX tag itself in the document. Under windows, a fill out field appears at the bottom of the window, just above the status line.

Examples

Twelve examples are available. All of the examples use METHOD=POST, and all but Example 12 will work with Windows Mosaic.

Return to the overview.

Robert B. Denny <rdenny@netcom.com>